No Fragments Archive 12: Textmags & Docs

home *** CD-ROM | disk | FTP | other *** search

/ No Fragments Archive 12: Textmags & Docs / nf_archive_12.iso / MAGS / SOURCES / ATARI_SRC.ZIP / atari source / AHDI / TTDRIVER / DB2SIDE.SLM < prev next >

Wrap

Text File | 2001-02-09 | 31.0 KB | 1,221 lines

5: U U 7CHAPTER 1 DB: THE ATARI DEBUGGER Db 5is a debugger for the Atari ST and TT series of 68000-family computers. It is intended to replace 7sid 5as the assembly-level debugger of choice. It is not a source-level debugger, but it does handle both Alcyon C and Mark Willi- ams C"187 (new and old) symbol table formats. Db can use any of the ST's character devices for its input and output, includ- ing the screen, the serial port, and the MIDI port. The I/O device is selected with a switch on the command line (or in the TTP window if started from the desktop). Db is capable of debugging programs running on one machine while the bulk of the debugger runs on another. This is called 6remote5 6debugging5, and permits debugging of operating systems while they boot, for example. This feature is described in the chapter REMOTE DEBUGGING. 7USAGE 5From a command shell, db can be started as follows: 7db 5[ 6options5 ] [ 6program5 [ 6args5 ... ] ] If started as a TTP program from the desktop, the arguments line looks the same without the word 7db 5at the beginning. 7OPTIONS 56Db5 can use many different devices for its input and output. This makes debugging graphics- and keyboard-oriented programs easier. These 6options5 on the command line select the output device to use: 7-g 5Use GEMDOS to access the ST screen and keyboard. This is the default case, but it does have limitations. See the section 7DB AND GEMDOS 5in the chapter 7OPERATING SYSTEM CONSIDERATIONS 5for more information. U ________________________ "187 Mark Williams C is a trademark of Mark Williams Company. U JANUARY, 1990 ATARI DEBUGGER DB DB ATARI DEBUGGER JANUARY, 1990 7-b56N5 Use the BIOS to access the ST screen and keyboard. Sometimes this helps when debugging a program which itself does BIOS I/O, because using GEMDOS calls can mess up type-ahead and the like. You can (optionally) specify which BIOS device to use by placing the BIOS device number after the 7-b5: "-b3" means "use BIOS calls for input and output, and use BIOS device number 3 (the MIDI port). The argu- ment is in decimal. Any number at all may be used here, including numbers which are not in fact BIOS device numbers; in this case, the debugger will probably crash, and it is likely that you will have to reset your machine. 7-s 5Use the serial (RS232) port. A terminal or an ST running a terminal program must be connected via a "null modem" cable, and its keyboard and screen are used for communicating with the debugger. (You can even use a modem connection to a terminal or computer, but this is extreme.) The baud rate, parity, etc. for the serial port must be set before starting the debugger in this mode. 7-m 5Use the MIDI port. An ST running a terminal program which uses the MIDI port must be connected with a double-MIDI cable (i.e. MIDI OUT -> MIDI IN and MIDI IN -> MIDI OUT). One such program is 7miditerm5, included on the distribution disk with the debugger. It is a minimal terminal emulator program, but it gets the job done. U In the last two modes, the debugger controls the serial or midi port hardware directly, without going through GEMDOS or the BIOS, so there are fewer limitations on debugging programs which use GEMDOS or the BIOS. However, the the limitations with respect to the operating system always apply, except when remote debugging. See the section 7DB AND GEMDOS 5in the chapter 7OPERATING SYSTEM CONSIDERATIONS 5for more information. Also, see 7iodev 5and 7bdev 5in the section on debugger variables. Each of the options 7-g5, 7-b5, 7-s5, and 7-m 5can be followed by the letter 7x5: this controls the printing of non-standard characters when using the 7d 5(dump) command. Non-standard characters are those with ASCII codes 128 and up. Normally, these are printed in the ASCII part of the dump command's output. When 7-s5, 7-m5, or 7-b 5with a device-number code is used, printing of these characters is suppressed, because they confuse most terminals. The presence of the letter 7x 5(e.g. 7-sx 5or 7-bx15) re-enables printing of these characters, which can be useful if your terminal is in fact another Atari computer with the same extended character set. The 7x 5modifier also con- trols the use of inverse video for error messages: if the Atari ST U 2 "189 1988,1990 Atari Corp. JANUARY, 1990 ATARI DEBUGGER DB extended character set is used, the VT52 code for inverse video will be used too. In addition, the following 6option5 controls loading of the initialization script: 7-i56file5 The debugger normally searches for and executes a startup file when it is run. The 7-i 5option disables this. With the optional 6file5 argu- ment, the normal startup file is not loaded, and 6file5 is loaded in its place. There must not be a space between the 7-i 5option and the 6file5 argument: "7-imyfile5". See the section 7USING THE DEBUGGER 5in this chapter for more information. D _______________________________________________________________ U Usage examples: db start the debugger; use GEMDOS for I/O. db -s myprog.prg -z use the serial port for I/O; load myprog.prg for execution, with the command-line argument -z. D _______________________________________________________________ |✓D |✓ |✓ |✓ |✓ |✓ | U |✓D |✓ |✓ |✓ |✓ |✓ | U 7TERMS 5Several terms are used throughout this document which must be defined here. The 6client5 is the program you are debugging. The 6head5 is the part of the debugger which handles all the user input and output. The commands you type are translated by the head into commands for the 6stub5. It is the stub which causes the client to run, processes breakpoints, and catches exceptions like bus error. The stub reports these events to the head, which reports them to you. When you are 6remote5 6debugging5, the head runs on the 6master5 machine, and the stub and client run on the 6slave5 machine. The head gives commands to the stub and receives the stub's responses through the 6communications5 layer, which actually talks over a MIDI cable. The term 6debugger5 is used to refer to the head, stub, and communications; in short, everything but the client (program) and the user (human). You cause the client to execute instructions with the 7g 5(go), 7t 5(trace), 7u 5(untrace), and 7v 5(verbose-trace) commands, collectively known as 6trace5/6go5 commands. A 6stop5 is anything which causes a trace/go to stop: a bus error, address error, or other processor 6exception5, a breakpoint whose count has reached zero, or a memory checkpoint which becomes true. Memory checkpoints are evaluated at times called 6opportunities5, which occur when "189 1988,1990 Atari Corp. 3 DB ATARI DEBUGGER JANUARY, 1990 processing exceptions, including the illegal-instruction exception caused by breakpoints and the trace exception which happens between instructions of a trace. You can put a list of commands to be executed in a file, and cause those commands to be executed by the debugger using the 7load 5command. Such files are called 6scripts5. Also, 6procedures5 consisting of debugger com- mands, arguments, and local variables are available. 7USING THE DEBUGGER 5When the debugger is started, it processes its GEMDOS command line first. If there are any 6options5 (like 7-m 5or 7-s5) they are checked and dealt with. Then, if there is a 6program5 argument, that program is loaded and set up for executing. It becomes the client. If there are any 6args5 they are placed in the client's basepage, as GEMDOS command-line arguments to it. When the client is completely set up and ready to run, the debugger prints out its basepage information (text size, environment pointer, etc.). This client set-up amounts to the same thing as using the 7exec 5command. The debugger then looks for and loads your configuration file (that is, it executes the commands found there; such files are called 6scripts5). The first place it looks is the current directory, for a file called 7db.rc5. If that file doesn't exist, it looks for the file named in the environment variable DBRC. If there is no such environment variable, it looks for the file 7db.rc 5in the directory named by the environment variable HOME. If none of these files exists, the debugger simply continues with the start- up procedure. When remote debugging, the autoload procedure is the same, except that the debugger looks for 7rdb.rc5, then the file named in the environment variable RDBRC, followed by 7rdb.rc 5in the HOME directory. In either case, the 7-i 5option on the debugger's command line inhibits the loading of a startup file. If the 7-i 5option has a 6file5 argument, that file is loaded instead. The debugger searches for the 6file5 in the current directory first, then in the HOME directory. Whether or not there was a 6program5 argument to execute and/or a startup file, the debugger ultimately displays its prompt, a colon (":"). Any time you see the colon prompt, the debugger is waiting for you to type a command line. Command lines consist of commands and their arguments. Multiple commands on one command line are separated by semicolons (";"). Multiple-letter commands must be separated from their arguments by a space (e.g. "7where 512322"), while single-letter commands don't need a space (e.g. "d12322" or "d 12322"). You can always use ^S (control-S) to stop the debugger's output and ^Q to start it again. You can usually use ^C to abort a command, especially commands which generate long listings. All numbers printed by the debugger are in hex. All numbers you type are 4 "189 1988,1990 Atari Corp. JANUARY, 1990 ATARI DEBUGGER DB assumed to be hex, unless prefixed with 7@ 5(decimal), 7^ 5(octal), or 7% 5(binary). When debugging programs compiled under Mark Williams C, you need to play a trick before you start the program. See the section 7DB AND MARK WILLIAMS C 5in the chapter 7OPERATING SYSTEM CONSIDERATIONS 5for more information. When 7remote debugging5, the debugger will display its version number, then wait for the stub to respond before loading the configuration script. U U "189 1988,1990 Atari Corp. 5 DB ATARI DEBUGGER JANUARY, 1990 U U 6 "189 1988,1990 Atari Corp. 7CHAPTER 2 EXPRESSIONS, RANGES, AND STRINGS 5This chapter describes how values are entered into the debugger, mostly as arguments to commands. An 6expression5 is something which boils down to a sin- gle numeric value. A 6range5 is something which boils down to a starting address and a length: a range of addresses. A 6string5 is something which boils down to a series of single-byte values. A section on each follows. 7EXPRESSIONS 5An 6expression5 can be used any time a numeric value (like an address or count) is expected. All expressions evaluate to 32-bit integers. Overflow is checked when reading a constant (so the hex constant $FFFFFFFF0 would cause and error because it requires 36 bits). Overflow is not checked in any other situation. There are two kinds of expressions: 6simple5 expres- sions and 6complex5 expressions. 7SIMPLE EXPRESSIONS 5Simple expressions contain no operators and are not enclosed in parentheses. There may not be any spaces in a simple expression. Simple expressions take one of the following forms: 6hex5 6constant5 7$56hex5 6constant5 A hex constant has the obvious value. The leading '7$5' is optional: with no prefix, a number is assumed to be hexadecimal. Hex constants consist of an optional sign (+ or -) followed by one or more of the digits 705-795, 7A5-7F5, and 7a5-7f5. Examples: 0, 1, 3FA, 13aD4, $ffffa4d0, $-5b30 (same as $ffffa4d0). 7@56decimal5 6constant5 A decimal constant begins with an at-sign ("7@5"), then an optional sign (+ or -), then one or more digits 705-795. It has the obvious value. Examples: @0, @99, @-32768 (same as ffff8000). 7^56octal5 6constant5 An octal constant begins with a circumflex (up-arrow, "7^5"), then an optional sign (+ or -), then one or more digits 705-775. It has the obvious value. JANUARY, 1990 ATARI DEBUGGER DB DB ATARI DEBUGGER JANUARY, 1990 Examples: ^0, ^77, ^20000000000 (same as 80000000). 7%56binary5 6constant5 A binary constant begins with a percent-sign ("7%5"), then an optional sign (+ or -), then one or more digits 705-715. It has the obvious value. Examples: %0, %1010, %1000000000000000 (same as 00008000). 7.56symbol5 A leading period ('7.5') indicates that what follows is a symbol specification. The value of the expression is the 32-bit value in the symbol's value field. A symbol specification can simply be the name of the symbol (e.g. ".start") or something more complex. See the chapter 7SYMBOLS AND DEBUGGER VARIABLES 5for more informa- tion. Examples: .main, .gemlib:xmain:__main:L3 7`56variable5 A leading backquote ('7`5') indicates that what follows is a debugger variable name. The value of this expression is the value in the corresponding debugger variable. See the chapter 7SYMBOLS AND DEBUGGER VARIABLES 5for more information. Examples: `d0, `clientbp, `mtype 7&56variable5 A leading ampersand ('7&5') indicates that what follows is a debugger variable name, and the value of this expression is the 6address5 of the storage for indicated variable 6in5 6the5 6stub5'6s5 6memory5. These variables should not be changed, since the debugger's local copy of the variable might overwrite your change. However, these addresses can be used in memory checks to set checkpoints on the values in registers. See the section 7DEBUGGER VARIABLES 5in the chapter 7SYMBOLS AND DEBUGGER VARIABLES 5(especially the subsection 7Client Registers5), and the section 7MEMORY CHECKPOINTS ON VALUES IN REGISTERS 5in the chapter 7THE CLIENT, BREAKPOINTS AND CHECKPOINTS: DETAIL 5for more information. Examples: &d1, &pc, &sr 7$ 5The dollar-sign alone is short for 7`$5. This temporary variable is set to the result of the last math command (that is, just an expression on the command line). In addition, the 7f 5(find) 8 "189 1988,1990 Atari Corp. JANUARY, 1990 ATARI DEBUGGER DB command sets 7$ 5to the address of the start of the first match. Example: $ 7COMPLEX EXPRESSIONS 5A 6complex5 6expression5 is a LISP-like expression containing parentheses, operators and operands in prefix notation. Unlike simple expressions, there may be spaces in a complex expression. The first element within the parentheses of a complex expression must be an operator. The second and subsequent elements must be expres- sions (simple or complex) which are used as operands for that opera- tor. In the following table of operators, "exp ..." means "one or more expressions." For the logical operators (and the 7if 5command), zero is "false" and anything nonzero is "true." The logical operators them- selves all return the number 1 if the expression is TRUE. U U "189 1988,1990 Atari Corp. 9 DB ATARI DEBUGGER JANUARY, 1990 D ______________________________________________________________ U FORMAT COMMENTS 7MATH 5(+ exp ...) Add the expressions together (- exp1 exp2) Subtract exp2 from exp1 (* exp ...) Multiply the expressions together (/ exp1 exp2) Divide exp1 by exp2 (% exp1 exp2) Return exp1 modulo exp2 7BITWISE 5(& exp ...) Bitwise AND the expressions together (| exp ...) Bitwise OR the expressions together (^ exp ...) Bitwise EXCLUSIVE OR the expressions (~ exp) Bitwise NOT (invert) the expression (>> exp1 exp2) exp1 >> exp2 (that is, exp1 shifted right by exp2 bits (zero fill)) (<< exp1 exp2) exp1 << exp2 (that is, exp1 shifted left by exp2 bits) 7LOGICAL 5(= exp1 exp2) TRUE if the expressions are equal (also ==) (&& exp1 exp2) Logical AND of the two expressions (|| exp1 exp2) Logical OR of the two expressions (^^ exp1 exp2) Logical EXCLUSIVE OR of the two expressions (! exp) Logical NOT of the expression (> exp1 exp2) TRUE if exp1 > exp2 (unsigned) (< exp1 exp2) TRUE if exp1 < exp2 (unsigned) (s> exp1 exp2) TRUE if exp1 > exp2 (signed) (s< exp1 exp2) TRUE if exp1 < exp2 (signed) 7MEMORY 5(lpeek exp) Returns the longword at address exp (wpeek exp) Returns the word at address exp (peek exp) Returns the byte at address exp D ______________________________________________________________ |✓D |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ | U |✓D |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ | U Here are some examples of complex expressions and how they evaluate: U U 10 "189 1988,1990 Atari Corp. JANUARY, 1990 ATARI DEBUGGER DB D ________________________________________________________________ U EXPRESSION VALUE COMMENTS (+ 2 3 3) 8 simple addition (- 7 5) 2 simple subtraction (* (+ 2 1) 3) 9 nested complex expressions (+ `clientbp 100) gives the client's text base (lpeek (+ 4 `d0 `a0)) the addressing mode 4(a0,d0.l) 8 (+ (+ 3 1) (/ (* 2 8) 4)) in algebraic notation: (3 + 1) + ((2 x 8) / 4) D ________________________________________________________________ |✓D |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ | U |✓D |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ | U 7RANGES 5A 6range5 is a way to specify a block of memory. A range consists of a start address and either an end address or a count. For most commands which take a range, the start and count values have defaults, so not all parts of the range need to be typed in. A fully-specified range can look like "6start57,56end5" or "6start57[56count57]5" (where 6start5, 6end5, and 6count5 are expressions, and the brackets and commas must be typed as shown). If the 6end5 address is present, it is the first address 6not5 included in the range: 7100,200 5specifies the range of addresses from 100 to 1FF, inclusive. Various parts of the full specification can be omitted. A range which uses the default start address looks like "7,56end5" (note the leading comma, showing that 6start5 was omitted) or "7[56count57]5" (the brackets set off 6count5 and show that 6start5 was omitted). If you want the default 6count5 the range just looks like "6start5" (which also looks like any other expression). Here are some examples and the ranges they specify, assuming the default start is 100 and the default count is 80 (all numbers are hex): D _________________________________________________________ U RANGE FIRST LAST COMMENTS 200[70] 200 26F no defaults; 6start57[56count57] 5form 200 200 27F default count of 80 [70] 100 16F default start; 7[56count57] 5form 80,100 80 FF no defaults; 6start57,56end5 form ,200 100 1FF default start; 7,56end5 form D _________________________________________________________ |✓D |✓ |✓ |✓ |✓ |✓ |✓ | U |✓D |✓ |✓ |✓ |✓ |✓ |✓ | U Sometimes the start and/or count fields have no defaults; in these cases, they must be specified. Also, the 6start57[56count57] 5form is not always allowed. This is the case for the 7g 5(go) command, where a count of bytes to execute does not make sense. The default start and count values are listed in the descriptions for all commands which take a range argument. U "189 1988,1990 Atari Corp. 11 DB ATARI DEBUGGER JANUARY, 1990 7STRINGS 56Strings5 are used mainly by the 7f 5(find) and 7s 5(memory set) commands. A string consists of characters surrounded by double-quotes (7"56string57"5) or single-quotes (7'56string57'5). The string acts like the sequence of bytes represented by the characters between the quotes, with the following escapes: D ___________________________________________________ U ESCAPE MEANING \b backspace ($08) \e escape ($1B) \f formfeed ($0C) \n linefeed ($0A) \r carriage return ($0D) \t tab ($09) \\ the single character backslash ($5C) \? the special "wildcard" escape (see 7find5) \xXX the byte $XX where XX is two hex digits D ___________________________________________________ |✓D |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ | U |✓D |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ |✓ | U Quotation marks are also used to set off parts of commands and keep semi- colons from splitting up a command. See the chapter 7PROCEDURES, IF, GOTO, DEFER, AND ALIAS 5for more information. U U 12 "189 1988,1990 Atari Corp. 7CHAPTER 3 THE CLIENT, BREAKPOINTS, AND CHECKPOINTS: AN OVERVIEW RUNNING THE CLIENT PROGRAM 5Once there is a client ready to run (loaded with the 7exec 5command or with a 6program5 argument on the debugger's command line), you can cause it to run with the 7g 5(go), 7t 5(trace), 7u 5(untrace), and 7v 5(verbose-trace) com- mands. Collectively, these are called trace/go commands. What follows are cursory descriptions. See the chapter 7THE CLIENT, BREAKPOINTS AND CHECKPOINTS: DETAIL 5for more information. The 7g 5(go) command runs the client at full speed. It will only stop when something exceptional happens, like hitting a breakpoint or causing a bus error. You can also stop it by hitting the stop button, if you have one. See the section 7STOP BUTTONS 5in the chapter 7REMOTE DEBUGGING 5for more information. The 7t 5(trace) and 7u 5(untrace) commands cause the client to execute just a few instructions (sometimes just one) and then stop and display the regis